{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n# Overview of axisartist toolkit\n\n\nThe axisartist toolkit tutorial.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>*axisartist* uses a custom Axes class\n   (derived from the mpl's original Axes class).\n   As a side effect, some commands (mostly tick-related) do not work.</p></div>\n\nThe *axisartist* contains a custom Axes class that is meant to support\ncurvilinear grids (e.g., the world coordinate system in astronomy).\nUnlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis\nto draw ticks, ticklines, etc., axisartist uses a special\nartist (AxisArtist) that can handle ticks, ticklines, etc. for\ncurved coordinate systems.\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png\n   :target: ../../gallery/axisartist/demo_floating_axis.html\n   :align: center\n   :scale: 50\n\n   Demo Floating Axis\n\nSince it uses special artists, some Matplotlib commands that work on\nAxes.xaxis and Axes.yaxis may not work.\n\n\naxisartist\n==========\n\nThe *axisartist* module provides a custom (and very experimental) Axes\nclass, where each axis (left, right, top, and bottom) have a separate\nassociated artist which is responsible for drawing the axis-line, ticks,\nticklabels, and labels.  You can also create your own axis, which can pass\nthrough a fixed position in the axes coordinate, or a fixed position\nin the data coordinate (i.e., the axis floats around when viewlimit\nchanges).\n\nThe axes class, by default, has its xaxis and yaxis invisible, and\nhas 4 additional artists which are responsible for drawing the 4 axis spines in\n\"left\", \"right\", \"bottom\", and \"top\".  They are accessed as\nax.axis[\"left\"], ax.axis[\"right\"], and so on, i.e., ax.axis is a\ndictionary that contains artists (note that ax.axis is still a\ncallable method and it behaves as an original Axes.axis method in\nMatplotlib).\n\nTo create an axes, ::\n\n  import mpl_toolkits.axisartist as AA\n  fig = plt.figure()\n  ax = AA.Axes(fig, [0.1, 0.1, 0.8, 0.8])\n  fig.add_axes(ax)\n\nor to create a subplot ::\n\n  ax = AA.Subplot(fig, 111)\n  fig.add_subplot(ax)\n\nFor example, you can hide the right and top spines using::\n\n  ax.axis[\"right\"].set_visible(False)\n  ax.axis[\"top\"].set_visible(False)\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisline3_001.png\n   :target: ../../gallery/axisartist/simple_axisline3.html\n   :align: center\n   :scale: 50\n\n   Simple Axisline3\n\nIt is also possible to add a horizontal axis. For example, you may have an\nhorizontal axis at y=0 (in data coordinate). ::\n\n    ax.axis[\"y=0\"] = ax.new_floating_axis(nth_coord=0, value=0)\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisartist1_001.png\n   :target: ../../gallery/axisartist/simple_axisartist1.html\n   :align: center\n   :scale: 50\n\n   Simple Axisartist1\n\nOr a fixed axis with some offset ::\n\n    # make new (right-side) yaxis, but with some offset\n    ax.axis[\"right2\"] = ax.new_fixed_axis(loc=\"right\",\n                  offset=(20, 0))\n\naxisartist with ParasiteAxes\n----------------------------\n\nMost commands in the axes_grid1 toolkit can take an axes_class keyword\nargument, and the commands create an axes of the given class. For example,\nto create a host subplot with axisartist.Axes, ::\n\n  import mpl_toolkits.axisartist as AA\n  from mpl_toolkits.axes_grid1 import host_subplot\n\n  host = host_subplot(111, axes_class=AA.Axes)\n\nHere is an example that uses ParasiteAxes.\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png\n   :target: ../../gallery/axisartist/demo_parasite_axes2.html\n   :align: center\n   :scale: 50\n\n   Demo Parasite Axes2\n\nCurvilinear Grid\n----------------\n\nThe motivation behind the AxisArtist module is to support a curvilinear grid\nand ticks.\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png\n   :target: ../../gallery/axisartist/demo_curvelinear_grid.html\n   :align: center\n   :scale: 50\n\n   Demo Curvelinear Grid\n\nFloating Axes\n-------------\n\nAxisArtist also supports a Floating Axes whose outer axes are defined as\nfloating axis.\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png\n   :target: ../../gallery/axisartist/demo_floating_axes.html\n   :align: center\n   :scale: 50\n\n   Demo Floating Axes\n\naxisartist namespace\n====================\n\nThe *axisartist* namespace includes a derived Axes implementation. The\nbiggest difference is that the artists responsible to draw axis line,\nticks, ticklabel and axis labels are separated out from the mpl's Axis\nclass, which are much more than artists in the original mpl. This\nchange was strongly motivated to support curvilinear grid. Here are a\nfew things that mpl_toolkits.axisartist.Axes is different from original\nAxes from mpl.\n\n* Axis elements (axis line(spine), ticks, ticklabel and axis labels)\n  are drawn by a AxisArtist instance. Unlike Axis, left, right, top\n  and bottom axis are drawn by separate artists. And each of them may\n  have different tick location and different tick labels.\n\n* gridlines are drawn by a Gridlines instance. The change was\n  motivated that in curvilinear coordinate, a gridline may not cross\n  axis-lines (i.e., no associated ticks). In the original Axes class,\n  gridlines are tied to ticks.\n\n* ticklines can be rotated if necessary (i.e, along the gridlines)\n\nIn summary, all these changes was to support\n\n* a curvilinear grid.\n* a floating axis\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png\n   :target: ../../gallery/axisartist/demo_floating_axis.html\n   :align: center\n   :scale: 50\n\n   Demo Floating Axis\n\n*mpl_toolkits.axisartist.Axes* class defines a *axis* attribute, which\nis a dictionary of AxisArtist instances. By default, the dictionary\nhas 4 AxisArtist instances, responsible for drawing of left, right,\nbottom and top axis.\n\nxaxis and yaxis attributes are still available, however they are set\nto not visible. As separate artists are used for rendering axis, some\naxis-related method in mpl may have no effect.\nIn addition to AxisArtist instances, the mpl_toolkits.axisartist.Axes will\nhave *gridlines* attribute (Gridlines), which obviously draws grid\nlines.\n\nIn both AxisArtist and Gridlines, the calculation of tick and grid\nlocation is delegated to an instance of GridHelper class.\nmpl_toolkits.axisartist.Axes class uses GridHelperRectlinear as a grid\nhelper. The GridHelperRectlinear class is a wrapper around the *xaxis*\nand *yaxis* of mpl's original Axes, and it was meant to work as the\nway how mpl's original axes works. For example, tick location changes\nusing set_ticks method and etc. should work as expected. But change in\nartist properties (e.g., color) will not work in general, although\nsome effort has been made so that some often-change attributes (color,\netc.) are respected.\n\nAxisArtist\n==========\n\nAxisArtist can be considered as a container artist with following\nattributes which will draw ticks, labels, etc.\n\n * line\n * major_ticks, major_ticklabels\n * minor_ticks, minor_ticklabels\n * offsetText\n * label\n\nline\n----\n\nDerived from Line2d class. Responsible for drawing a spinal(?) line.\n\nmajor_ticks, minor_ticks\n------------------------\n\nDerived from Line2d class. Note that ticks are markers.\n\nmajor_ticklabels, minor_ticklabels\n----------------------------------\n\nDerived from Text. Note that it is not a list of Text artist, but a\nsingle artist (similar to a collection).\n\naxislabel\n---------\n\nDerived from Text.\n\nDefault AxisArtists\n===================\n\nBy default, following for axis artists are defined.::\n\n  ax.axis[\"left\"], ax.axis[\"bottom\"], ax.axis[\"right\"], ax.axis[\"top\"]\n\nThe ticklabels and axislabel of the top and the right axis are set to\nnot visible.\n\nFor example, if you want to change the color attributes of\nmajor_ticklabels of the bottom x-axis ::\n\n  ax.axis[\"bottom\"].major_ticklabels.set_color(\"b\")\n\nSimilarly, to make ticklabels invisible ::\n\n  ax.axis[\"bottom\"].major_ticklabels.set_visible(False)\n\nAxisArtist provides a helper method to control the visibility of ticks,\nticklabels, and label. To make ticklabel invisible, ::\n\n  ax.axis[\"bottom\"].toggle(ticklabels=False)\n\nTo make all of ticks, ticklabels, and (axis) label invisible ::\n\n      ax.axis[\"bottom\"].toggle(all=False)\n\nTo turn all off but ticks on ::\n\n      ax.axis[\"bottom\"].toggle(all=False, ticks=True)\n\nTo turn all on but (axis) label off ::\n\n      ax.axis[\"bottom\"].toggle(all=True, label=False))\n\nax.axis's __getitem__ method can take multiple axis names. For\nexample, to turn ticklabels of \"top\" and \"right\" axis on, ::\n\n      ax.axis[\"top\",\"right\"].toggle(ticklabels=True))\n\nNote that 'ax.axis[\"top\",\"right\"]' returns a simple proxy object that translate above code to something like below. ::\n\n      for n in [\"top\",\"right\"]:\n        ax.axis[n].toggle(ticklabels=True))\n\nSo, any return values in the for loop are ignored. And you should not\nuse it anything more than a simple method.\n\nLike the list indexing \":\" means all items, i.e., ::\n\n      ax.axis[:].major_ticks.set_color(\"r\")\n\nchanges tick color in all axis.\n\nHowTo\n=====\n\n1. Changing tick locations and label.\n\n  Same as the original mpl's axes.::\n\n   ax.set_xticks([1,2,3])\n\n2. Changing axis properties like color, etc.\n\n  Change the properties of appropriate artists. For example, to change\n  the color of the ticklabels::\n\n    ax.axis[\"left\"].major_ticklabels.set_color(\"r\")\n\n3. To change the attributes of multiple axis::\n\n    ax.axis[\"left\",\"bottom\"].major_ticklabels.set_color(\"r\")\n\n   or to change the attributes of all axis::\n\n    ax.axis[:].major_ticklabels.set_color(\"r\")\n\n4. To change the tick size (length), you need to use\n    axis.major_ticks.set_ticksize method. To change the direction of\n    the ticks (ticks are in opposite direction of ticklabels by\n    default), use axis.major_ticks.set_tick_out method.\n\n    To change the pad between ticks and ticklabels, use\n    axis.major_ticklabels.set_pad method.\n\n    To change the pad between ticklabels and axis label,\n    axis.label.set_pad method.\n\nRotation and Alignment of TickLabels\n====================================\n\nThis is also quite different from the original mpl and can be\nconfusing. When you want to rotate the ticklabels, first consider\nusing \"set_axis_direction\" method. ::\n\n  ax1.axis[\"left\"].major_ticklabels.set_axis_direction(\"top\")\n  ax1.axis[\"right\"].label.set_axis_direction(\"left\")\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction01_001.png\n   :target: ../../gallery/axisartist/simple_axis_direction01.html\n   :align: center\n   :scale: 50\n\n   Simple Axis Direction01\n\nThe parameter for set_axis_direction is one of [\"left\", \"right\",\n\"bottom\", \"top\"].\n\nYou must understand some underlying concept of directions.\n\n 1. There is a reference direction which is defined as the direction\n    of the axis line with increasing coordinate.  For example, the\n    reference direction of the left x-axis is from bottom to top.\n\n    .. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_demo_step01_001.png\n       :target: ../../gallery/axisartist/axis_direction_demo_step01.html\n       :align: center\n       :scale: 50\n\n       Axis Direction Demo - Step 01\n\n   The direction, text angle, and alignments of the ticks, ticklabels and\n   axis-label is determined with respect to the reference direction\n\n 2. *ticklabel_direction* is either the right-hand side (+) of the\n    reference direction or the left-hand side (-).\n\n    .. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_demo_step02_001.png\n       :target: ../../gallery/axisartist/axis_direction_demo_step02.html\n       :align: center\n       :scale: 50\n\n       Axis Direction Demo - Step 02\n\n 3. same for the *label_direction*\n\n    .. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_demo_step03_001.png\n       :target: ../../gallery/axisartist/axis_direction_demo_step03.html\n       :align: center\n       :scale: 50\n\n       Axis Direction Demo - Step 03\n\n 4. ticks are by default drawn toward the opposite direction of the ticklabels.\n\n 5. text rotation of ticklabels and label is determined in reference\n    to the *ticklabel_direction* or *label_direction*,\n    respectively. The rotation of ticklabels and label is anchored.\n\n    .. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_demo_step04_001.png\n       :target: ../../gallery/axisartist/axis_direction_demo_step04.html\n       :align: center\n       :scale: 50\n\n       Axis Direction Demo - Step 04\n\nOn the other hand, there is a concept of \"axis_direction\". This is a\ndefault setting of above properties for each, \"bottom\", \"left\", \"top\",\nand \"right\" axis.\n\n ========== =========== ========= ========== ========= ==========\n    ?           ?        left      bottom      right      top\n ---------- ----------- --------- ---------- --------- ----------\n axislabel   direction      '-'       '+'        '+'      '-'\n axislabel   rotation      180         0          0       180\n axislabel   va           center    top       center     bottom\n axislabel   ha           right    center      right     center\n ticklabel   direction      '-'       '+'        '+'      '-'\n ticklabels  rotation       90         0        -90       180\n ticklabel   ha           right    center      right     center\n ticklabel   va           center   baseline    center   baseline\n ========== =========== ========= ========== ========= ==========\n\nAnd, 'set_axis_direction(\"top\")' means to adjust the text rotation\netc, for settings suitable for \"top\" axis. The concept of axis\ndirection can be more clear with curved axis.\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_axis_direction_001.png\n   :target: ../../gallery/axisartist/demo_axis_direction.html\n   :align: center\n   :scale: 50\n\n   Demo Axis Direction\n\nThe axis_direction can be adjusted in the AxisArtist level, or in the\nlevel of its child artists, i.e., ticks, ticklabels, and axis-label. ::\n\n  ax1.axis[\"left\"].set_axis_direction(\"top\")\n\nchanges axis_direction of all the associated artist with the \"left\"\naxis, while ::\n\n  ax1.axis[\"left\"].major_ticklabels.set_axis_direction(\"top\")\n\nchanges the axis_direction of only the major_ticklabels.  Note that\nset_axis_direction in the AxisArtist level changes the\nticklabel_direction and label_direction, while changing the\naxis_direction of ticks, ticklabels, and axis-label does not affect\nthem.\n\nIf you want to make ticks outward and ticklabels inside the axes,\nuse invert_ticklabel_direction method. ::\n\n   ax.axis[:].invert_ticklabel_direction()\n\nA related method is \"set_tick_out\". It makes ticks outward (as a\nmatter of fact, it makes ticks toward the opposite direction of the\ndefault direction). ::\n\n   ax.axis[:].major_ticks.set_tick_out(True)\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction03_001.png\n   :target: ../../gallery/axisartist/simple_axis_direction03.html\n   :align: center\n   :scale: 50\n\n   Simple Axis Direction03\n\nSo, in summary,\n\n * AxisArtist's methods\n    * set_axis_direction : \"left\", \"right\", \"bottom\", or \"top\"\n    * set_ticklabel_direction : \"+\" or \"-\"\n    * set_axislabel_direction : \"+\" or \"-\"\n    * invert_ticklabel_direction\n * Ticks' methods (major_ticks and minor_ticks)\n    * set_tick_out : True or False\n    * set_ticksize : size in points\n * TickLabels' methods (major_ticklabels and minor_ticklabels)\n    * set_axis_direction : \"left\", \"right\", \"bottom\", or \"top\"\n    * set_rotation : angle with respect to the reference direction\n    * set_ha and set_va : see below\n * AxisLabels' methods (label)\n    * set_axis_direction : \"left\", \"right\", \"bottom\", or \"top\"\n    * set_rotation : angle with respect to the reference direction\n    * set_ha and set_va\n\nAdjusting ticklabels alignment\n------------------------------\n\nAlignment of TickLabels are treated specially. See below\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_ticklabel_alignment_001.png\n   :target: ../../gallery/axisartist/demo_ticklabel_alignment.html\n   :align: center\n   :scale: 50\n\n   Demo Ticklabel Alignment\n\nAdjusting pad\n-------------\n\nTo change the pad between ticks and ticklabels ::\n\n  ax.axis[\"left\"].major_ticklabels.set_pad(10)\n\nOr ticklabels and axis-label ::\n\n  ax.axis[\"left\"].label.set_pad(10)\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_pad_001.png\n   :target: ../../gallery/axisartist/simple_axis_pad.html\n   :align: center\n   :scale: 50\n\n   Simple Axis Pad\n\nGridHelper\n==========\n\nTo actually define a curvilinear coordinate, you have to use your own\ngrid helper. A generalised version of grid helper class is supplied\nand this class should suffice in most of cases. A user may provide\ntwo functions which defines a transformation (and its inverse pair)\nfrom the curved coordinate to (rectilinear) image coordinate. Note that\nwhile ticks and grids are drawn for curved coordinate, the data\ntransform of the axes itself (ax.transData) is still rectilinear\n(image) coordinate. ::\n\n    from mpl_toolkits.axisartist.grid_helper_curvelinear \\\n         import GridHelperCurveLinear\n    from mpl_toolkits.axisartist import Subplot\n\n    # from curved coordinate to rectlinear coordinate.\n    def tr(x, y):\n        x, y = np.asarray(x), np.asarray(y)\n        return x, y-x\n\n    # from rectlinear coordinate to curved coordinate.\n    def inv_tr(x,y):\n        x, y = np.asarray(x), np.asarray(y)\n        return x, y+x\n\n    grid_helper = GridHelperCurveLinear((tr, inv_tr))\n\n    ax1 = Subplot(fig, 1, 1, 1, grid_helper=grid_helper)\n\n    fig.add_subplot(ax1)\n\nYou may use matplotlib's Transform instance instead (but a\ninverse transformation must be defined). Often, coordinate range in a\ncurved coordinate system may have a limited range, or may have\ncycles. In those cases, a more customized version of grid helper is\nrequired. ::\n\n    import mpl_toolkits.axisartist.angle_helper as angle_helper\n\n    # PolarAxes.PolarTransform takes radian. However, we want our coordinate\n    # system in degree\n    tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()\n\n    # extreme finder :  find a range of coordinate.\n    # 20, 20 : number of sampling points along x, y direction\n    # The first coordinate (longitude, but theta in polar)\n    #   has a cycle of 360 degree.\n    # The second coordinate (latitude, but radius in polar)  has a minimum of 0\n    extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,\n                                                     lon_cycle = 360,\n                                                     lat_cycle = None,\n                                                     lon_minmax = None,\n                                                     lat_minmax = (0, np.inf),\n                                                     )\n\n    # Find a grid values appropriate for the coordinate (degree,\n    # minute, second). The argument is a approximate number of grids.\n    grid_locator1 = angle_helper.LocatorDMS(12)\n\n    # And also uses an appropriate formatter.  Note that,the\n    # acceptable Locator and Formatter class is a bit different than\n    # that of mpl's, and you cannot directly use mpl's Locator and\n    # Formatter here (but may be possible in the future).\n    tick_formatter1 = angle_helper.FormatterDMS()\n\n    grid_helper = GridHelperCurveLinear(tr,\n                                        extreme_finder=extreme_finder,\n                                        grid_locator1=grid_locator1,\n                                        tick_formatter1=tick_formatter1\n                                        )\n\nAgain, the *transData* of the axes is still a rectilinear coordinate\n(image coordinate). You may manually do conversion between two\ncoordinates, or you may use Parasite Axes for convenience.::\n\n    ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)\n\n    # A parasite axes with given transform\n    ax2 = ParasiteAxesAuxTrans(ax1, tr, \"equal\")\n    # note that ax2.transData == tr + ax1.transData\n    # Anything you draw in ax2 will match the ticks and grids of ax1.\n    ax1.parasites.append(ax2)\n\n.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png\n   :target: ../../gallery/axisartist/demo_curvelinear_grid.html\n   :align: center\n   :scale: 50\n\n   Demo Curvelinear Grid\n\nFloatingAxis\n============\n\nA floating axis is an axis one of whose data coordinate is fixed, i.e,\nits location is not fixed in Axes coordinate but changes as axes data\nlimits changes. A floating axis can be created using\n*new_floating_axis* method. However, it is your responsibility that\nthe resulting AxisArtist is properly added to the axes. A recommended\nway is to add it as an item of Axes's axis attribute.::\n\n    # floating axis whose first (index starts from 0) coordinate\n    # (theta) is fixed at 60\n\n    ax1.axis[\"lat\"] = axis = ax1.new_floating_axis(0, 60)\n    axis.label.set_text(r\"$\\theta = 60^{\\circ}$\")\n    axis.label.set_visible(True)\n\nSee the first example of this page.\n\nCurrent Limitations and TODO's\n==============================\n\nThe code need more refinement. Here is a incomplete list of issues and TODO's\n\n* No easy way to support a user customized tick location (for\n  curvilinear grid). A new Locator class needs to be created.\n\n* FloatingAxis may have coordinate limits, e.g., a floating axis of x\n  = 0, but y only spans from 0 to 1.\n\n* The location of axislabel of FloatingAxis needs to be optionally\n  given as a coordinate value. ex, a floating axis of x=0 with label at y=1\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
